Step 1 - Create a contacts list and get contacts from a data source

In this step of the tutorial you first create the Grid List Box node which you use as a contacts list. You then set the Grid List Box to receive the contacts data from a data source.

Assets for the tutorial

The starting point of this tutorial is the List box.kzproj Kanzi Studio project file stored in the <KanziWorkspace>/Tutorials/List box/Start/Tool_project directory.

The <KanziWorkspace>/Tutorials/List box/Completed/Tool_project directory contains the completed project of this tutorial.

The starting point project contains the content you need to complete this tutorial:

Create a Grid List Box

In this section you create the Grid List Box which you use to show the list of contacts.

To create a Grid List Box:

  1. In Kanzi Studio open the project stored in the <KanziWorkspace>/Tutorials/List box/Start/Tool_project directory.
  2. In the Project press Alt and right-click the RootPage node, select Grid List Box 2D, and name it ContactsList.
  3. In the Project select the ContactsList node and in the Properties set the Item Template property to ContactItem.
    With the Item Template property you set which prefab template you want a Grid List Box node to use for its items.

Get the items from a data source

In this section you use a data source to populate the ContactsList you created in the previous section.

In Kanzi the list box nodes use virtualization to load and show at once only the number of items you want to show. The list box loads new items and removes the ones not visible anymore when user scrolls the list box.

In Kanzi Studio you can manually add or remove items in a list box node. However, use that only for lists with a small amount of static number of items and for prototyping. If you know that the number of items in a list box is going to change during application runtime, always use a data source to populate list box nodes.

To get the list items from a data source:

  1. In the Project select the ContactsList node, in the Properties add the Data Context property, and set it to XML data source.
    By setting the Data Context property you tell your application from which data source it receives data.
  2. In the main menu select Window > Data Sources.
    Use the Data Sources window to manage the data sources in your project.
  3. In the Project select the ContactsList node, from the Data Sources window drag the XML data source > contacts data object, and drop it to the Items Source property of the ContactsList node in the Properties.
    The Items Source property sets the source which provides the data for the items that the ContactsList node shows.
  4. In the Prefabs in the ContactItem prefab select the ContactPhoto node, from the Data Sources window drag the XML data source > contacts > Item > contact > photo data object, and drop it on the Image property in the Properties. This data object provides the photo for each contact item in the contacts list.
    When you drag and drop a data object on a property that has a single field, Kanzi Studio creates a binding that binds the value of that property to the data object you dropped on that property.
    The value for the Image property of the ContactPhoto node now comes from the XML data source photo data object.
  5. Repeat the previous step for the ContactItem > Container > ContactName node but use the XML data source > contacts > Item > contact > name data object.
    This data object provides the name for each contact item in the contacts list.

The ContactsList node now receives the photos and names for the contact items from the ContactsList.xml using the XML data source data source. In the Preview you can see the contact data.

Define the layout for the list box content

In this section you set the layout for the ContactsList node and the list items to present the content in the application.

To define the layout for the list box content, in the Project select the ContactsList node and in the Properties set:

The Preview now shows the updated layout for the list box and its items. To change the name of a contact in the contacts list, in a text editor change the values in the ContactsList.xml file, and save the ContactsList.xml file.

Set how the Grid List Box scrolls its items

In this section you define how the Grid List Box scrolls its items and set the selected item to move to the center of the Grid List Box area.

To set how the Grid List Box scroll its items:

  1. In the Project select the ContactsList node and in the Properties set the list box to scroll the selected item to the center of the node area:
  2. In the Project select the ContactsList node and in the Properties add and set the Scroll Sensitivity property to 360.
    You set the Scroll Sensitivity property to match the value of the Layout Height property of the ContactsList node.
    When you set the Scroll Sensitivity property of the Grid List Box node to match the size of the node layout in the scroll direction, the Grid List Box node scrolls the same amount as the user drags the pointer.

In the Preview when you select a list item, the list box brings that item to the center of its area.

< INTRODUCTION
NEXT STEP >